Premium Analytics: port the Locations stats widget by dognose24 · Pull Request #49513 · Automattic/jetpack

dognose24 · 2026-06-10T08:03:39Z

Fixes #

Proposed changes

Ports the Locations module from Jetpack Stats (Calypso's client/my-sites/stats/features/modules/stats-locations) into the Premium Analytics customizable dashboard as a jpa/locations widget, on the dashboard introduced by #49502.

Widget (widgets/locations/): world map (@automattic/charts GeoChart) + a country leaderboard (widgets-toolkit LeaderboardChart: flags, share bars), presented like the visitors-by-location widget. Attributes: range (trailing-window presets, default last 30 days; date is omitted so the endpoint anchors "today" in the site's timezone) and max. Loading/empty states and a bundled sample-data fallback (marked "Sample data") when live data isn't available.
Data goes through the stats-admin proxy: GET /jetpack/v4/stats-app/sites/{blogId}/stats/country-views (summarized), normalized by a widget-local port of Calypso's statsCountryViews normalizer (country/summary branch).
Blog id bridge (src/stats-config.php): exposes the connected site's blog id to the dashboard page as window.configData.blog_id (the Odyssey convention) via an inline script on wp-api-fetch, hooked to both page-init actions. Stats widgets need the id because the proxy bakes it into the route. No-ops (→ sample data) when the site isn't connected.
Wires internal-package resolution for widget code via link:packages/* deps on the parent manifest, so widgets can consume @jetpack-premium-analytics/widgets-toolkit; widgets resolve imports against the parent manifest.

Deviations from upstream (documented in the widget README)

Country-level only for v1 — the Regions/Cities views and the country filter are follow-ups; stats-admin's dedicated …/stats/location-views/(country|region|city) route makes them reachable when we get there.
Calypso-only infrastructure is intentionally not ported: Redux state + QuerySiteStats, calypso-router, the gating/upsell flow, the Jetpack-version upgrade prompt, and analytics event tracking.
The map renders via the in-repo @automattic/charts GeoChart (react-google-charts) instead of Calypso's hand-rolled Google Charts loader; countries resolution needs no Maps API key.
Widget id is jpa/locations (host namespace).

Known limitations / follow-ups

The blog-id bridge is expected to be subsumed by the PA data package integration (feat(premium-analytics): port data package from next-woocommerce-analytics #49263 landed the package; stats widgets aren't on it yet).
Widget title/attribute labels in widget.json/widget.ts aren't translatable yet — pending an i18n convention for the widget contract (same situation as hello-world).
Regions/Cities + country filter, per above.

Related product discussion/links

Builds on [Do not merge] Premium Analytics: introduce the customizable widget dashboard #49502 (base branch)
Linear: WOOA7S-1491 (parent: WOOA7S-1458)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Requires pnpm ^11.5 and Node ^24.15. After checkout, run pnpm install to reconcile the lockfile.

Build: pnpm --filter @automattic/jetpack-premium-analytics build — hello-world and locations widgets both build, and build/widgets/registry.php registers jpa/locations.
Typecheck: pnpm --filter @automattic/jetpack-premium-analytics typecheck — only the pre-existing useSelect/preferences errors in widget-dashboard/widget-primitives remain (present on the base branch; verified with the widget removed).
On a Jetpack-connected test site with the package synced:
1. Open the Premium Analytics admin page → view source: window.configData.blog_id = <wpcom blog id>; is inlined before wp-api-fetch runs.
2. Customize → Add widget → insert "Locations" (map-marker icon) → the world map and the flag leaderboard render side by side with live data and no "Sample data" badge.
3. DevTools → Network: GET /wp-json/jetpack/v4/widget-modules lists jpa/locations; widgets/locations/render.min.js loads as a separate chunk on mount; one …/stats-app/sites/{id}/stats/country-views?period=day&…&summarize=1 request fires.
4. On a disconnected site (or with the request blocked): the widget falls back to the bundled sample list with the "Sample data" badge instead of breaking.

github-actions · 2026-06-10T08:11:21Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Copilot

Pull request overview

Ports Jetpack Stats’ Locations module into Premium Analytics as a new jpa/locations dashboard widget, including UI (GeoChart + ranked list), a widget-local data hook/normalizer, and the server-side blog-id bridge needed to call the stats-admin proxy route.

Changes:

Add the jpa/locations widget (metadata/type definition, render UI, styles, README, and widget-local package manifest).
Add a useLocationViews hook that fetches /jetpack/v4/stats-app/sites/{blogId}/stats/country-views and normalizes the summarized response, with a sample-data fallback.
Expose the connected WordPress.com blog id on the dashboard page via window.configData.blog_id and wire required JS deps (@automattic/charts, @wordpress/api-fetch) + lockfile.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
projects/packages/premium-analytics/widgets/locations/widget.ts	Declares the widget type, icon, presentation, and attributes (period/max).
projects/packages/premium-analytics/widgets/locations/widget.json	Adds widget metadata for discovery/inserter (title/description/category).
projects/packages/premium-analytics/widgets/locations/use-location-views.ts	Implements fetch + normalization + sample-data fallback for country views.
projects/packages/premium-analytics/widgets/locations/style.module.css	Styles for widget layout, placeholder, list rows, and sample badge.
projects/packages/premium-analytics/widgets/locations/render.tsx	Renders the GeoChart + ranked country list with loading/empty states.
projects/packages/premium-analytics/widgets/locations/README.md	Documents scope, upstream deviations, and data/API dependencies.
projects/packages/premium-analytics/widgets/locations/package.json	Declares widget-local dependencies (charts, api-fetch, ui, etc.).
projects/packages/premium-analytics/src/stats-config.php	Adds inline config to expose `window.configData.blog_id` on the dashboard page.
projects/packages/premium-analytics/src/class-analytics.php	Loads the new stats-config bridge during package init.
projects/packages/premium-analytics/package.json	Adds `@automattic/charts` and `@wordpress/api-fetch` to package deps.
projects/packages/premium-analytics/changelog/add-locations-widget	Adds a changelog entry for the new widget.
pnpm-lock.yaml	Updates lockfile for the new/updated workspace dependencies.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

+		rows.push( {
+			// ’ in country names breaks the geo visualization, so normalize it.
+			label: view.location || info.country_full.replace( /’/g, "'" ),
+			countryCode: view.country_code,
+			countryFull: info.country_full,
+			value: view.views,
+			region: info.map_region ?? '',
+		} );


+		// is demoable. See README for the package support this needs.
+		if ( ! blogId ) {
+			setState( {
+				data: SAMPLE_LOCATIONS.slice( 0, max ),


+					return;
+				}
+				setState( {
+					data: SAMPLE_LOCATIONS.slice( 0, max ),


jp-launch-control · 2026-06-12T01:01:44Z

Code Coverage Summary

No summary data is available for parent commit 909996e, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for 909996e is available.

Full summary · PHP report

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

+		rows.push( {
+			// ’ in country names breaks the geo visualization, so normalize it.
+			label: view.location || info.country_full.replace( /’/g, "'" ),
+			countryCode: view.country_code,
+			countryFull: info.country_full,
+			value: view.views,
+			region: info.map_region ?? '',
+		} );


+		if ( ! blogId ) {
+			setState( {
+				data: SAMPLE_LOCATIONS.slice( 0, max ),
+				isLoading: false,
+				isError: false,
+				isSample: true,
+			} );
+			return;
+		}


+			.catch( () => {
+				if ( cancelled ) {
+					return;
+				}
+				setState( {
+					data: SAMPLE_LOCATIONS.slice( 0, max ),
+					isLoading: false,
+					isError: true,
+					isSample: true,
+				} );
+			} );


Private, source-consumed copy of @wordpress/grid until core publishes it.

Private, source-consumed copy of @wordpress/widget-primitives until core publishes it.

Private, source-consumed dashboard engine; depends on jetpack-widget-primitives and jetpack-grid.

Renders the WidgetDashboard engine via wp-build, bundling the grid/primitives/dashboard packages.

useWidgetTypes drives discovery via /wp/v2/widget-modules; hello-world builds as a lazy-loaded script module.

Hook the page boot-dependencies filter so widget modules reach the import map; move the endpoint to the jetpack/v4 namespace.

@wordpress/grid and widget-primitives references in widget-dashboard JSDoc/comments/README, per the faithful-source sync policy.

Port the Jetpack Stats Locations module (country-level v1) from Calypso into the Premium Analytics customizable dashboard as a jpa/locations widget: GeoChart world map + ranked country list, fetching live data through the stats-admin proxy. Expose the connected blog id to the dashboard page (src/stats-config.php) so stats widgets can build their proxy requests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the period attribute with date-range presets (today / 7 / 30 / 365 days) summarized server-side, and omit the date param so the window anchors to today in the site's own timezone. period=day with num=1 showed only the current UTC day, which renders empty most mornings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the plain country list with the widgets-toolkit LeaderboardChart (flags, share bars) beside the map, wrapped in GlobalChartsProvider since LeaderboardChart does not self-provide the charts context the way GeoChart does. Wire internal-package resolution for widget code via link:packages/* deps on the parent manifest. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dognose24 added the [Status] In Progress label Jun 10, 2026

dognose24 self-assigned this Jun 10, 2026

github-actions Bot added [Package] Premium Analytics Docs labels Jun 10, 2026

dognose24 requested a review from Copilot June 10, 2026 15:01

Copilot started reviewing on behalf of dognose24 June 10, 2026 15:01 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

nerrad force-pushed the update/pa-introduce-customize-dashboard branch from 91aa9fb to 909996e Compare June 11, 2026 22:51

dognose24 force-pushed the add/wooa7s-1491-port-stats-module-locations branch from ea86b35 to d4fdf61 Compare June 12, 2026 00:58

dognose24 requested a review from Copilot June 12, 2026 01:08

Copilot started reviewing on behalf of dognose24 June 12, 2026 01:09 View session

Copilot AI reviewed Jun 12, 2026

View reviewed changes

retrofox added 8 commits June 12, 2026 11:38

add jetpack-grid package ported from core

d6585d4

Private, source-consumed copy of @wordpress/grid until core publishes it.

add jetpack-widget-primitives package ported from core

ac22c29

Private, source-consumed copy of @wordpress/widget-primitives until core publishes it.

add jetpack-widget-dashboard package ported from core

42fa025

Private, source-consumed dashboard engine; depends on jetpack-widget-primitives and jetpack-grid.

wire premium-analytics dashboard route with static hello-world widget

787944d

Renders the WidgetDashboard engine via wp-build, bundling the grid/primitives/dashboard packages.

add dynamic widget registry and REST endpoint

c092386

useWidgetTypes drives discovery via /wp/v2/widget-modules; hello-world builds as a lazy-loaded script module.

fix widget module loading and REST namespace

43cb828

Hook the page boot-dependencies filter so widget modules reach the import map; move the endpoint to the jetpack/v4 namespace.

localize vendored package refs in docs

1cd0ea8

@wordpress/grid and widget-primitives references in widget-dashboard JSDoc/comments/README, per the faithful-source sync policy.

add changelog entries for dashboard packages

d060b2d

louwie17 force-pushed the update/pa-introduce-customize-dashboard branch from 909996e to d060b2d Compare June 12, 2026 02:39

github-actions Bot added [JS Package] Grid [JS Package] Widget Dashboard [JS Package] Widget Primitives RNA labels Jun 12, 2026

dognose24 and others added 3 commits June 12, 2026 11:58

dognose24 force-pushed the add/wooa7s-1491-port-stats-module-locations branch from cae7f67 to 89d5fc8 Compare June 12, 2026 02:59

nerrad force-pushed the update/pa-introduce-customize-dashboard branch from d060b2d to 5bb6dd9 Compare June 12, 2026 08:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Premium Analytics: port the Locations stats widget#49513

Premium Analytics: port the Locations stats widget#49513
dognose24 wants to merge 11 commits into
update/pa-introduce-customize-dashboardfrom
add/wooa7s-1491-port-stats-module-locations

dognose24 commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jp-launch-control Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dognose24 commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Deviations from upstream (documented in the widget README)

Known limitations / follow-ups

Related product discussion/links

Does this pull request change what data or activity we track or use?

Testing instructions

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jp-launch-control Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dognose24 commented Jun 10, 2026 •

edited

Loading

jp-launch-control Bot commented Jun 12, 2026 •

edited

Loading